Microsoft CodeView and Utilities
================================
CHAPTER 6 ___ EXAMINING DATA AND EXPRESSIONS
(Second half)

6.3  Dump Commands

The CodeView debugger has several commands for dumping data from memory to the
screen (or other output device).  The Dump commands are listed below.

Command		Command Name
---------------------------
D		Dump (size is the default type)
DB		Dump Bytes
DA		Dump ASCII
DI		Dump Integers
DU		Dump Unsigned Integers
DW		Dump Words
DD		Dump Double Words
DS		Dump Short Reals
DL		Dump Long Reals
DT		Dump 10-Byte Reals

<*> Mouse

The Dump commands cannot be executed with the mouse.

<*> Keyboard

The Dump commands cannot be executed with keyboard commands.


<*> Dialog

To execute a Dump command with a dialog command, enter a command line with the
following syntax:

D[type] [address|range]
The  type  is a one-letter specifier that indicates the type of the data to be
dumped.  The Dump commands expect either a starting   address or   range of
memory.  If the starting  address  is given, the commands assume a default
range (usually determined by the size of the dialog window) starting at
address.  If  range  is given, the commands dump from the start to the end of
range.  The maximum size of  range  is 32K.

If neither  address  nor  range  is given, the commands assume the current
dump address as the start of the range and the default size associated with 
the size of the object as the length of the range.  The Dump Real commands
have a default range size of one real number.  The other Dump commands have a
default size determined by the size of the dialog window (if you are in window
mode), or a default size of 128 bytes otherwise.

The current dump address is the byte following the last byte specified in the
previous Dump command.  If no Dump command has been used during the session,
the dump address is the start of the data segment (DS).  For example, if you
enter the Dump Words command with no argument as the words (128 bytes) of data
declared in the data segment.  If you repeat the same command, the debugger
displays the next 64 words following the ones dumped by the first command.
----
Note
----
If the value in memory cannot be evaluated as a real number, the Dump
commands that display real numbers (Dump Short Reals, Dump Long Reals, or
Dump 10-Byte Reals) will display a number containing one of the following
character sequences: #NAN, #INF, or #IND.  NAN (not a number) indicates
that the data cannot be evaluated as a real number.  INF (infinity)
indicates that the data evaluates to infinity.  IND (indefinite) indicates
that the data evaluates to an indefinite number.
====

Sections 6.3.1-6.3.10 discuss the variations of the Dump commands in order of
the size of data they display.

6.3.1  Dump

<*> Syntax

D [address | range]

The Dump command displays the contents of memory at the specified   address
or in the specified   range   of addresses.  The command dumps data in the
format of the default type.  The default type is the last type specified with
a Dump, Enter, Watch Memory, or Tracepoint Memory command.  If none of these
commands has been entered during the session, the default type is bytes.

The Dump command displays one or more lines, depending on the address or range
specified.  Each line displays the address of the first item displayed.  The
Dump command must be separated by at least one space from any   address  or
range  value.  For example, to dump memory starting at symbol a, use the
command D a, not Da.  The second syntax would be interpreted as the Dump ASCII
command.

6.3.2  Dump Bytes

<*> Syntax

DB [address | range]

The Dump Bytes command displays the hexadecimal and ASCII values of the bytes
at the specified  address  or in the specified  range  of addresses.  The
command displays one or more lines, depending on the address or range
supplied.

Each line displays the address of the first byte in the line, followed by up
to 16 hexadecimal byte values.  The byte values are immediately followed by
the corresponding ASCII values.  The hexadecimal values are separated by
spaces, except the eighth and ninth values, which are separated by a dash (-).
ASCII values are printed without separation.  Unprintable ASCII values (less
than 32 or greater than 126) are displayed as dots.  No more than 16 hexa-
decimal values are displayed in a line.  The command displays values and
characters until the end of the  range  or, if no  range  is given, until the
first 128 bytes have been displayed.

<*> Example

>DB 0 36
3D5E:0000 53 6F 6D 65 20 6C 65 74-74 65 72 73 20 61 6E 64 Some letters and
3D5E:0010 20 6E 75 6D 62 65 72 73-3A 00 10 EA 89 FC FF EF  numbers:.......
3D5E:0020 00 F0 00 CA E4
>

The example above displays the byte values from DS:0 to DS:36 (36 decimal is
equivalent to 24 hexadecimal).  The data segment is assumend if no segment is
given.  ASCII characters are shown on the right.

6.3.3  Dump ASCII

<*> Syntax

DA [address | range]

The Dump ASCII command displays the ASCII characters at a specified  address
or in a specified  range  of addresses.  The command displays one or more
lines of characters, depending on the   address  or   range  specified.

If no ending address is specified, the command dumps either 128 bytes or all
bytes preceding the first null byte, whichever comes first.  Up to 64 
characters per line are displayed.  Unprintable characters, such as carriage
returns and line feeds, are displayed as dots.  ASCII characters less than 32
and greater than 126 in number are unprintable.

<*> Examples

>DA 0
3D7C:0000  Some letters and numbers:
>

The example above displays the ASCII values of the bytes starting at DS:0.
Since no ending address is given, values are displayed up to the first null
byte.

>DA 0 36
3D7C:0000  Some letters and numbers:...........
>

In the example above, an ending address is given, so the characters from DS:0
to DS:36 (24 hexadecimal) are shown.  Unprintable characters are shown as
dots.

6.3.4  Dump Integers

<*> Syntax

DI [address | range]

The Dump Integers command displays the signed decimal values of the words
(two-byte values) starting at  address  or in the specified  range  of
addresses.  The command displays one or more lines, depending on the address
or range specified.  Each line displays the address of the first integer in
the line, followed by up to eight signed decimal words.  The values are
separated by spaces.  The command displays values until the end of the  range
or until the first 64 two-byte integers have been displayed, whichever comes
first.
----
Note
----
In this manual an integer is considered a two-byte value, since the
CodeView debugger assumes that integer size.  Note that a default FORTRAN
integer is a four-byte value.
====

<*> Example

>DI 0 36
3D5E:0000   28499  25965  27680  29797  25972  29554  24864  25710
3D5E:0010   28192  28021  25954  29554     58  -5616   -887  -4097
3D5E:0020   -4096 -13824   2532
>

The example above displays the byte values from DS:0 to DS:36 (24 hexa-
decimal).  Compare the signed decimal numbers at the end of this dump with the
same values shown as unsigned integers in Section 6.3.5 below.

6.3.5  Dump Unsigned Integers

<*> Syntax

DU [address | range]

The Dump Unsigned Integers command displays the unsigned decimal values of the
words (two-byte values) starting at  address  or in the specified  range  of
addresses.  The command displays one or more lines, depending on the address
or range specified.  Each line displays the address of the first unsigned
integer in the line, followed by up to eight decimal words.  The values are
separated by spaces.  The command displays values until the end of the  range
or until the first 64 unsigned integers have been displayed, whichever comes
first.

<*> Example

>DU 0 36                                      
3D5E:0000   28499  25965  27680  29797  25972  29554  24864  25710
3D5E:0010   28192  28021  25954  29554     58  59920  64649  61439
3D5E:0020   61440  51712   2532
>

The example above displays the byte values from DS:0 to DS:36 (24 hexa-
decimal).  Compare the unsigned decimal numbers at the end of this dump with
the same values shown as signed integers in Section 6.3.4 above.

6.3.6  Dump Words

<*> Syntax

DW [address | range]

The Dump Words command displays the hexadecimal values of the words (two-byte
values) starting at  address  or in the specified  range of addresses.  The
command displays one or more lines, depending on the address or range
specified.  Each line displays the address of the first word in the line,
followed by up to eight hexadecimal words.  The hexadecimal values are
separated by spaces.  The command displays values until the end of the  range
or until the first 64 words have been displayed, whichever comes first.

<*> Example

>DW 0 36
3D5E:0000  6F53 656D 6C20 7465 6574 7372 6120 646E
3D5E:0010  6E20 6D75 6562 7372 003A EA10 FC89 EFFF
3D5E:0020  F000 CA00 09E4
>

The example above displays the word values from DS:0 to DS:36 (24 hexa-
decimal).  No more than eight values per line are displayed.

6.3.7  Dump Double Words

<*> Syntax

DD [address | range]

The Dump Double Words command displays the hexadecimal values of the double
words (four-byte values) starting at  address  or in the specified  range of
addresses.

The command displays one or more lines, depending on the address or range
specified.  Each line displays the address of the first double word in the
line, followed by up to four hexadecimal double-word values.  The words of
each double word are separated by a colon.  The values are separated by
spaces.  The command displays values until the end of the  range or until the
first 32 double words have been displayed, whichever comes first.

<*> Example

>DD 0 36
3D5E:0000  656D:6F53 7465:6C20 7372:6574 646E:6120
3D5E:0010  6D75:6E20 7372:6562 EA10:003A EFFF:FC89
3D5E:0020  CA00:F000 6F73:09E4
>

The example above displays the double-word values from DS:0 to DS:36 (24 hexa-
decimal).  No more than four double-word values per line are displayed.

6.3.8  Dump Short Reals

<*> Syntax

DS [address | range]

The Dump Short Reals command displays the hexadecimal and decimal values of
the short (four byte) floating-point numbers at  address  or in the specified
range of addresses.

The command displays one or more lines, depending on the address or range
specified.  Each line displays the address of the floating-point number in the
first column.  Next, the hexadecimal values of the bytes in the number are
shown, followed by the decimal value of the number.  The hexadecimal values
are separated by spaces.  The decimal value has the following form:

[-]digit.digitsE{+|-}exponent

If the number is negative, it will have a minus sign; positive numbers have no
sign.  The first digit of the number is followed by a decimal point.  Six
decimal places are shown following the decimal point.  The letter E follows
the decimal digits, and marks the start of a three-digit signed exponent.

The command displays at least one value.  If a  range  is specified, all
values in the range are displayed.

<*> Example

>DS SPI
5E68:0100  DB 0F 49 40  3.141593E+000
>

The example above displays the short-real floating-point number at the address
of the variable SPI.  Only one value is displayed per line.

6.3.9  Dump Long Reals

<*> Syntax

DL [address | range]

The Dump Long Reals command displays the hexadecimal and decimal values of the
long (eight byte) floating-point numbers at the specified  address  or in the
specified  range  of addresses.

The command displays one or more lines, depending on the address or range
specified.  Each line displays the address of the floating-point number in the
first column.  Next, the hexadecimal values of the bytes in the number are
shown, followed by the decimal value of the number.  The hexadecimal values
are separated by spaces.

The decimal value has the following form:

[-]digit.digitsE{+|-}exponent

If the number is negative, it will have a minus sign; positive numbers have no
sign.  The first digit of the number is followed by a decimal point.  Six
decimal places are shown following the decimal point.  The letter E follows
the decimal digits, and marks the start of a three-digit signed exponent.  The
command displays at least one value.  If a range is specified, all values in
the range are displayed.

<*> Example

>DL LPI
5E68:0200   11 2D 44 54 FB 21 09 40   3.141593E+000
>

The example above displays the long-real floating-point number at the address
of the variable LPI.  Only one value per line is displayed.

6.3.10  Dump 10-Byte Reals

<*> Syntax

DT [address | range]

The Dump 10-Byte Reals command displays the hexadecimal and decimal values of
the 10-byte floating-point numbers at the specified address or in the speci-
fied range of addresses.
The command displays one or more lines, depending on the address or range
specified.  Each line displays the address of the floating-point number in the
first column.  Next, the hexadecimal values of the bytes in the number are
shown, followed by the decimal value of the number.  The hexadecimal values
are separated by spaces.

The decimal value has the following form:

[-]digit.digitsE{+|-}exponent

If the number is negative, it will have a minus sign; positive numbers have no
sign.  The first digit of the number is followed by a decimal point.  Six
decimal places are shown following the decimal point.  The letter E follows
the decimal digits, and marks the start of a three-digit signed exponent.

The command displays at least one value.  If a range is specified, all values
in the range are displayed.

<*> Example

>DT TPI
5E68:0300  DE 87 68 21 A2 DA 0F C9 00 40   3.141593E+000
>

The example above displays the 10-byte floating-point number at the address of
the variable TPI.  Only one number per line is displayed.

6.4  Compare Memory Command

The Compare Memory command provides a convenient way for comparing two blocks
of memory, specified by absolute addresses.  This command is primarily of
interest to programmers using assembly mode; however, it can be useful to
anyone who wants to compare efficiently two large areas of data, such as
arrays.

<*> Mouse

The Compare Memory command cannot be executed with the mouse.

<*> Keyboard

The Compare Memory command cannot be executed with a keyboard command.

<*> Dialog

To compare two blocks of memory, enter a command line with the following
syntax:

C range address

The bytes in the memory locations specified by range are compared with the
corresponding bytes in the memory locations beginning at address.  If one or
more pairs of corresponding bytes do not match, each pair of mismatched bytes
is displayed.
<*> Examples

>C 100 01FF 300		;* hexadecimal radix assumed
39BB:0102 0A 00 39BB:0302
39BB:0108 0A 01 39BB:0308
>

The first example (in which hexadecimal is assumed to be the default radix)
compares the block of memory from 100 to 1FF with the block of memory from 300
to 3FF.  It indicates that the third and ninth bytes differ in the two areas
of memory.

>C arr1(1) L 100  arr2(1)	;* BASIC/FORTRAN notation used
>

The second example compares the 100 bytes starting at the address of arr1(1),
with the 100 bytes starting at address of arr2(1).  The CodeView debugger
produces no output in response, so this indicates that the first 100 bytes of
each array are identical.  (Using C language, this example would be entered as
C arr1[0] L 100 arr2[0].)
----
Note
----
You can enter the Compare Memory command using any radix you like; how-
ever, any output will still be in hexadecimal format.
====

6.5  Search Memory Command

The Search Memory command (not to be confused with the Search command
discussed in Section 11.6) scans a specified area of memory, looking for
specific byte values.  It is primarily of interest to programmers using
assembly mode, and to users who want to test for the presence of specific
values within a range of data.

<*> Mouse

The Search Memory command cannot be executed with the mouse.

<*> Keyboard

The Search Memory command cannot be executed with a keyboard command.

<*> Dialog

To search a block of memory, enter the Search Memory command with the
following syntax:

S range list

The debugger will search the specified range of memory locations for the byte
values specified in the list.  If bytes with the specified values are found,
then the debugger displays the addresses of each occurrence of bytes in the
list.

The list can have any number of bytes.  Each byte value must be separated by a
space or comma, unless the list is an ASCII string.  If the list contains more
than one byte, then the Search Memory command looks for a series of bytes that
precisely match the order and value of bytes in  list.  If found, then the be-
ginning address of each such series is displayed.

<*> Examples

>S buffer L 1500 "error"
2BBA:0404
2BBA:05E3
2BBA:0604
>

The first example displays the address of each memory location containing the
string   error.  The command searches the first 1500 bytes at the address
specified by   buffer.  The string was found at the three addresses displayed
by the CodeView debugger.

>S DS:100 200 0A		;* hexadecimal radix assumed
3CBA:0132
3CBA:01C2
>
The second example displays the address of each memory location that contains
the byte value 0A in the range DS:0100 to DS:0200 (hexadecimal).  The value
was found at two addresses.

6.6  Port Input Command

The Port Input command reads and displays a byte from a specified hardware
port.  It is primarily of interest ot assembly language programmers writing
hardware-specific programs.

<*> Mouse

 The Port Input command cannot be executed with the mouse.

<*> Keyboard

The Port Input command cannot be executed with a keyboard command.

<*> Dialog

The Port Input command is executed with the following syntax:

I port

The byte is read and displayed from the specified  port, which can be any 16-
bit address.

<*> Examples

>I 2F8  ;* hexadecimal radix assumed
E8
The preceding example reads input port, number 2F8, and displays the result,
E8.  You may enter the port address using any radix you want, but the result
will always be displayed in current radix.

The Port Input command is often used in conjunction with the Port Output
command, which is described in Section 10.5.

6.7  Register Command

The Register command has two functions.  It displays the contents of the
central processing unit (CPU) registers.  It can also change the values of the
registers.  The display features of the Register command are explained here.
The modification features of the command are explained in Chapter 10,
"Modifying Code or Data."

<*> Mouse

To display the registers with the mouse, point to View on the menu bar, press
a mouse button and drag the highlight down to the Registers selection, ;and
then release the button.  The register window will appear on the right side of
the screen.  If the register window is already on the screen, the same command
removes it.

<*> Keyboard

To display the registers using a keyboard command in window mode, press the F2
key.  The register window will appear on the right side of the screen.  If the
register window is already on the screen, the same command will remove it.

In sequential mode, the F2 key will display the current status of the
registers. (This produces the same effect as entering the Register dialog
command with no argument.)

<*> To display the registers in the dialog window (or sequentially in
sequential mode), enter a command line with the following syntax:

R

The current values of all registers and flags are displayed.  The instruction
at the address pointed to by the current CS and IP register values is also
shown. (The Register command can also be given with arguments, but only when
used to modify registers, as explained in Chapter 10, "Modifying Code or
Data.")

If the display mode is source (S+) or mixed (S&) (see Section 9.1, "Set Mode
Command," for more information), the current source line is also displayed by
the Register command.  If an operand of the instruction contains memory
expressions or immediate data, the CodeView debugger will evaluate operands
and show the value to the right of the instruction.  This value is referred to
as the "effective address," and is also displayed at the bottom of the register
window.  If the CS and IP registers are currently at a breakpoint location,
the register display will indicate the breakpoint number.

In sequential mode, the Trace (T), Program Step (P), and Go (G) commands show
registers in the same format as the Register command.

<*> Examples

>S&
mixed
>R
AX=0005  BX=299E  CX=0000  DX=0000  SP=3800  BP=380E  SI=0070  DI=40D1
DS=5067  ES=5067  SS=5067  CS=4684  IP=014F  NV UP IE PL NZ NA PO NC
35:                         VARIAN = (N*SUMXSQ-SUMX**2)/(N-1)
4684:014F 8B5E06        MOV     BX,Word Ptr [BP+06]     ;BR1  SS:3814=299E

The example above displays all register and flag values, as well as the
instruction at the address pointed to by the CS and IP registers.  Because the
mode has been set to mixed (S&), the current source line is also shown.  The
example is from a FORTRAN program, but applies equally will to BASIC and C
programs.

>S-
assembly
>R
AX=0005  BX=299E  CX=0000  DX=0000  SP=3800  BP=380E  SI=0070  DI=40D1
DS=5067  ES=5067  SS=5067  CS=4684  IP=014F  NV UP EI PL NZ NA PO NC
4684:014F 8B5E06        MOV     BX,Word Ptr [BP+06]     ;BR1  SS:3814=299E
>

In the example above, the display mode is set to assembly (S-), so no source
line is shown.  Note the breakpoint number at the right of the last line,
indicating that the current address in at Breakpoint 1.

6.8  8087 Command

The 8087 command dumps the contents of the 8087 registers.  If you do not have
an 8087 or 80287 coprocessor chip on your system, then this command will dump
the contents of the pseudoregisters created by the compiler's emulator
routines.  This command is useful only if you have an 8087 or 80287 chip
installed, or if your executable file includes math routines from a Microsoft
8087-emulator library.
----
Note
----
This section does not attempt to explain how the registers of the Intel
8087 and 80287 processors are organized or how they work.  In order to
interpret the command output, you must learn about the chip from an Intel
reference manual or other book on the subject.  Since the Microsoft emu-
lator routines mimic the behavior of the 8087 coprocessor, these refer-
ences will apply to emulator routines as well as to the chips themselves.
====

<*> Mouse

The 8087 command cannot be executed with the mouse.


<*> Keyboard

The 8087 command cannot be executed with ta keyboard command.

<*> Dialog

To display the status of the 8087 or 80287 chip (or floating-point emulator
routines) with a dialog command, enter a command line with the following
syntax:

7

The current status of the chip is displayed when you enter the command.  In
window mode, the output is to the dialog window.  If you do not have an 8087
or 80287 chip, and are not linking to an emulator library, then the debugger
will report the error message   floating point not loaded.

The following example shows a display for a machine that actually has an 8087
or 80287 chip.  The example at the end of the section shows the same display
for a machine using an emulator library instead of an actual math coprocessor.

<*> 8087 Example

>7
cControl 037F  (Projective closure, Round nearest, 64-bit precision)
                        iem=0 pm=1 um=1 om=1 zm=q dm=1 im=1
cStatus  6004  cond=1000 top=4 pe=0 ue=0 oe=0 ze=1 de=0 ie=0
Tag     A1FF  instruction=59380  operand=59360  opcode=D9EE
Stack         Exp  Mantissa           Value
cST(3) special 7FFF 8000000000000000 = + Infinity
cST(2) special 7FFF 0101010101010101 = + Not a Number
cST(1) valid   4000 C90FDAA22168C235 = +3.141592265110390E+000
cST(0) zero    0000 0000000000000000 = +0.000000000000000E+000
>

In the example above, the first line of the dump shows the current closure
method, rounding method, and the precision.  The number 037F is the hexa-
decimal value in the control register.  The rest of the line interprets the
bits of the number.  The closure method can be either projective (as in the
example) or affine.  The rounding method can be either rounding to the nearest
even number (as in the example), rounding down, rounding up, or using the chop
method of rounding (truncating toward zero).  The precision may be 64 bits (as
in the example), 53 bits, or 24 bits.

The second line of the display indicates whether each exception mask bit is
set or cleared.  The masks are interrupt-enable mask (iem), precision mask
(pm), underflow mask (um), overflow mask (om), zero divide mask (zm),
denormalized-operand mask (dm), and invalid-operation mask (im).

The third line of the display shows the hexadecimal value of the status
register (6004 in the example), and then interprets the bits of the register.
The condition code (cond) in the example is the binary number 1000.  The top
of the stack (top) is register 4 (shown in decimal).  The other bits shown are
precision exception (pe), underflow exception (ue), overflow exception (oe),
zero-divide exception (ze), denormalized-operand exception (de), and invalid-
operation exception (ie).

The fourth line of the display first shows the hexadecimal value of the tag
register (A1FF in the example).  It then gives the hexadecimal values of the
instruction (59380), and the operation code, or opcode, (D9EE).

The fifth line is a heading for the subsequent lines, which contain the
contents of each 8087 or 80287 stack register.  The registers in the example
contain four types of numbers that may be held in these registers.  Starting
from the bottom, register 0 contains zero.  Register 1 contains a valid real
number.  Its exponent (in hexadecimal) is 4000 and its mantissa is
C90FDAA22168C235.  The number is shown in scientific notation in the rightmost
column.  Register 2 contains a value that cannot be interpreted as a number,
and register 3 contains infinity.

The c that precedes Control, Status, and each of the ST listings indicates
that an actual math-coprocessor chip is in use.  If emulator routines were in
use instead of a chip, then each c prefix would be replaced by e, as in the
next example.

<*> Floating-Point Emulator Example

>7
eControl 037F  (Projective closure, Round nearest, 64-bit precision)
                        iem=0 pm=1 um=1 om=1 zm=1 dm=1 im=1
eStatus  6004  cond=1000 top=4 pe=0 ue=0 oe=0 ze=1 de=0 ie=0
Tag     A1FF  instruction=59380  operand=59360  opcode=D9EE
Stack         Exp  Mantissa           Value
eST(3) special 7FFF 8000000000000000 = + Infinity
eST(2) special 7FFF 0101010101010101 = + Not a Number
eST(1) valid   4000 C90FDAA22168C235 = +3.141592265110390E+000
eST(0) zero    0000 0000000000000000 = +0.000000000000000E+000
>

Note the e at the beginning of the first, third, sixth, seventh, eighth, and
ninth lines.  Aside from this replacement of the c prefix by e, the emulator
display is the same as the corresponding display for an 8087 chip.


.end of chapter.